<!DOCTYPE html>
<html lang="en">
<head>
  <title>Maven verticle factory - Vert.x</title>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta content="width=device-width, initial-scale=1.0" name="viewport">
  <meta content="Vert.x is a tool-kit for building reactive applications on the JVM." name="description">
  <link href="http://vertx.io/stylesheets/docs.css" media="screen" rel="stylesheet">
  <link href="http://vertx.io/stylesheets/font-awesome.min.css" media="screen" rel="stylesheet">
  <link href="http://vertx.io/javascripts/styles/rainbow.min.css" media="screen" rel="stylesheet">
  <!-- IE 6-8 support of HTML 5 elements -->
  <!--[if lt IE 9]>
  <script src="http://static.jboss.org/theme/js/libs/html5/pre3.6/html5.min.js"></script>
  <![endif]-->

  <link rel="apple-touch-icon" sizes="57x57" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-57x57.png">
  <link rel="apple-touch-icon" sizes="60x60" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-60x60.png">
  <link rel="apple-touch-icon" sizes="72x72" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-72x72.png">
  <link rel="apple-touch-icon" sizes="76x76" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-76x76.png">
  <link rel="apple-touch-icon" sizes="114x114" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-114x114.png">
  <link rel="apple-touch-icon" sizes="120x120" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-120x120.png">
  <link rel="apple-touch-icon" sizes="144x144" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-144x144.png">
  <link rel="apple-touch-icon" sizes="152x152" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-152x152.png">
  <link rel="apple-touch-icon" sizes="180x180" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-180x180.png">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-32x32.png" sizes="32x32">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/android-chrome-192x192.png" sizes="192x192">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-96x96.png" sizes="96x96">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-16x16.png" sizes="16x16">
  <link rel="manifest" href="http://vertx.io/assets/favicons/vertx-favicon-7/manifest.json">
  <link rel="mask-icon" href="http://vertx.io/assets/favicons/vertx-favicon-7/safari-pinned-tab.svg" color="#5bbad5">
  <meta name="msapplication-TileColor" content="#7d3194">
  <meta name="msapplication-TileImage" content="http://vertx.io/assets/favicons/vertx-favicon-7/mstile-144x144.png">
  <meta name="theme-color" content="#ffffff">

  <link href="http://fonts.googleapis.com/css?family=Ubuntu:400,500,700,400italic" rel="stylesheet" type="text/css">
  <link rel="alternate" type="application/rss+xml" title="RSS"
     href="http://vertx.io/feed.xml">
  <script>
    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
    })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
    ga('create', 'UA-30144458-1', 'auto');
    ga('create', 'UA-71153120-1', 'auto', 'tracker');
    ga('send', 'pageview');
    ga('tracker.send', 'pageview');
  </script>
</head>
<body>

<a href="http://www.reactivemanifesto.org/" id="reactive-manifesto-banner">
  <img style="border: 0; position: fixed; right: 0; top:0; z-index: 9000"
    src="http://d379ifj7s9wntv.cloudfront.net/reactivemanifesto/images/ribbons/we-are-reactive-black-right.png">
</a>

<a id="skippy" class="sr-only sr-only-focusable" href="#content"><div class="container"><span class="skiplink-text">Skip to main content</span></div></a>

<header class="navbar navbar-default navbar-static-top" id="top" role="banner">
  <div class="container">
    <div class="navbar-header">
      <button class="navbar-toggle collapsed" type="button" data-toggle="collapse" data-target="#vertx-navbar-collapse">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <a href="http://vertx.io/" class="navbar-brand"><img alt="Brand" src="http://vertx.io/assets/logo-sm.png"></a>
    </div>
    <nav class="collapse navbar-collapse" id="vertx-navbar-collapse">
      <ul class="nav navbar-nav navbar-right">
        <li><a href="http://vertx.io/download/">Download</a></li>
        <li><a href="http://vertx.io/docs/">Documentation</a></li>
        <li><a href="https://github.com/vert-x3/wiki/wiki">Wiki</a></li>
        <li><a href="http://vertx.io/community/">Community</a></li>
        <li><a href="http://vertx.io/materials/">Materials</a></li>
        <li><a href="http://vertx.io/blog/">Blog</a></li>        
      </ul>
    </nav>
  </div>
</header>



  <div class="page-header" id="content">
    <div class="container">
      <div class="row">
        <div class="col-sm-12">
          <h1>Maven verticle factory</h1>
          
        </div>
      </div>
    </div>
  </div>




<div id="content">
  <div class="container docs-content">
    <div class="row">
      <div class="col-sm-12 col-md-push-9 col-md-3 hidden-xs hidden-sm">
        <div id="sidebar" data-spy="affix">
          <ul class="sectlevel1">
<li><a href="#_usage">Usage</a></li>
<li><a href="#_declaring_the_verticle_factory_programmatically">Declaring the Verticle Factory programmatically</a></li>
<li><a href="#_configuring_repositories">Configuring repositories</a>
<ul class="sectlevel2">
<li><a href="#_programmatically">Programmatically</a></li>
</ul>
</li>
<li><a href="#_remote_repository_access_through_authenticated_https">Remote repository access through authenticated https</a>
<ul class="sectlevel2">
<li><a href="#_using_system_properties">Using system properties</a></li>
<li><a href="#_programmatically_2">Programmatically</a></li>
</ul>
</li>
<li><a href="#_remote_repository_access_through_proxies">Remote repository access through proxies</a>
<ul class="sectlevel2">
<li><a href="#_using_system_properties_2">Using system properties</a></li>
<li><a href="#_programmatically_3">Programmatically</a></li>
</ul>
</li>
<li><a href="#_configuring_authentication">Configuring authentication</a></li>
<li><a href="#_configuring_remote_snapshot_refresh_policy">Configuring Remote Snapshot Refresh Policy</a></li>
<li><a href="#_customizing_the_resolver">Customizing the resolver</a></li>
</ul>
        </div>
      </div>
      <div class="col-sm-12 col-md-pull-3 col-md-9">
        <div class="toc hidden-md hidden-lg">
          <h2>Table of Contents</h2>
          <ul class="sectlevel1">
<li><a href="#_usage">Usage</a></li>
<li><a href="#_declaring_the_verticle_factory_programmatically">Declaring the Verticle Factory programmatically</a></li>
<li><a href="#_configuring_repositories">Configuring repositories</a>
<ul class="sectlevel2">
<li><a href="#_programmatically">Programmatically</a></li>
</ul>
</li>
<li><a href="#_remote_repository_access_through_authenticated_https">Remote repository access through authenticated https</a>
<ul class="sectlevel2">
<li><a href="#_using_system_properties">Using system properties</a></li>
<li><a href="#_programmatically_2">Programmatically</a></li>
</ul>
</li>
<li><a href="#_remote_repository_access_through_proxies">Remote repository access through proxies</a>
<ul class="sectlevel2">
<li><a href="#_using_system_properties_2">Using system properties</a></li>
<li><a href="#_programmatically_3">Programmatically</a></li>
</ul>
</li>
<li><a href="#_configuring_authentication">Configuring authentication</a></li>
<li><a href="#_configuring_remote_snapshot_refresh_policy">Configuring Remote Snapshot Refresh Policy</a></li>
<li><a href="#_customizing_the_resolver">Customizing the resolver</a></li>
</ul>
        </div>
        <div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>The Maven verticle factory is an implementation of verticle factory loading a service dynamically from a Maven
repository at run-time.</p>
</div>
<div class="paragraph">
<p>It&#8217;s useful if you don&#8217;t want to package all your service dependencies at build-time into
your application, but would rather install and deploy them dynamically at run-time when they are requested.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_usage">Usage</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Vert.x picks up <code>VerticleFactory</code> implementations from the classpath, so you just need to make sure the
vertx-maven-service-factory jar file on the classpath. First you need to add the Maven verticle factory to your application&#8217;s
classpath. If you are using a fat jar, you can use the following dependencies:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Maven (in your <code>pom.xml</code>):</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-xml" data-lang="xml">&lt;dependency&gt;
  &lt;groupId&gt;io.vertx&lt;/groupId&gt;
  &lt;artifactId&gt;vertx-maven-service-factory&lt;/artifactId&gt;
  &lt;version&gt;3.3.3&lt;/version&gt;
&lt;/dependency&gt;</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>Gradle (in your <code>build.gradle</code> file):</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-groovy" data-lang="groovy">compile 'io.vertx:vertx-maven-service-factory:3.3.3'</code></pre>
</div>
</div>
<div class="paragraph">
<p>This <code>VerticleFactory</code> uses the prefix <code>maven:</code> to select it when deploying services.
The service identifier is made up of the Maven co-ordinates of the artifact that contains the service, e.g.
<code>com.mycompany:main-services:1.2</code> followed by a double colon <code>::</code> followed by the service name. The service name is
used to find the service descriptor file inside the artifact which is named by the service name with a <code>.json</code>
extension. This is explained in the the
<a href="http://vertx.io/docs/vertx-service-factory/java">vert.x service factory documentation</a>.</p>
</div>
<div class="paragraph">
<p>For example, to deploy a service that exists in Maven artifact <code>com.mycompany:my-artifact:1.2</code> called <code>my-service</code> you
would use the string <code>maven:com.mycompany:main-services:1.2::my-service</code>. Given this string, the verticle factory</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>uses the Aether client try and locate the artifact <code>com.mycompany:my-artifact:1.2</code> and all its dependencies in
the configured Maven repositories and download and install it locally if it&#8217;s not already installed.</p>
</li>
<li>
<p>constructs a classpath including all those artifacts and creates a classloader with that classpath</p>
</li>
<li>
<p>service using the <a href="http://vertx.io/docs/vertx-service-factory/java">vert.x service factory</a>.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Note that if the current Vert.x classpath contains already an artifact, then this dependency will not be
overridden and will be effectively used. Vert.x does not attempt to make some class loading magic, conflicts
should be resolved by modifying the Vert.x classpath to not contain this dependency.</p>
</div>
<div class="paragraph">
<p>The Service Verticle Factory will look for a descriptor file called <code>my-service.json</code> (in the previous example) on
the constructed classpath to actually load the service.</p>
</div>
<div class="paragraph">
<p>Given a service identifier the service can be deployed programmatically e.g.:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">vertx.deployVerticle("maven:com.mycompany:my-artifact:1.2::my-service", options);</code></pre>
</div>
</div>
<div class="paragraph">
<p>Or can be deployed on the command line with:</p>
</div>
<hr>
<div class="paragraph">
<p>vertx run maven:com.mycompany:my-artifact:1.2::my-service
---</p>
</div>
<div class="paragraph">
<p>The service name (<code>my-service</code>) can be omitted when the <em>META-INF/MANIFEST</em> in the jar containing the
service contains a <code>Main-Verticle</code> entry that declares the verticle to run:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">vertx.deployVerticle("maven:com.mycompany:my-artifact:1.2", options);</code></pre>
</div>
</div>
<div class="paragraph">
<p>And the manifest contains:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Main-Verticle: service:my-service</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_declaring_the_verticle_factory_programmatically">Declaring the Verticle Factory programmatically</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You can also declare the verticle factory programmatically:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">vertx.registerVerticleFactory(new MavenVerticleFactory());</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_configuring_repositories">Configuring repositories</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The Maven local repository location can be configured using the <code>vertx.maven.localRepo</code> system property - this should
point to the local repository directory on disc. The default value is: <code>{user.home}/.m2/repository</code></p>
</div>
<div class="paragraph">
<p>The list of remote repositories can be configured using the <code>vertx.maven.remoteRepos</code> system property - this should
contain a <strong>space</strong> separated list of urls to the remote repositories. The default value is
<code><a href="https://repo.maven.apache.org/maven2/" class="bare">https://repo.maven.apache.org/maven2/</a> <a href="https://oss.sonatype.org/content/repositories/snapshots/" class="bare">https://oss.sonatype.org/content/repositories/snapshots/</a></code></p>
</div>
<div class="sect2">
<h3 id="_programmatically">Programmatically</h3>
<div class="paragraph">
<p>You can also configure the repositories programmatically by passing a <code><a href="../../apidocs/io/vertx/maven/ResolverOptions.html">ResolverOptions</a></code>
object to the constructor of the <code><a href="../../apidocs/io/vertx/maven/MavenVerticleFactory.html">MavenVerticleFactory</a></code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">vertx.registerVerticleFactory(new MavenVerticleFactory(
    new ResolverOptions()
        .setLocalRepository(local)
        .setRemoteRepositories(remotes))
);</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_remote_repository_access_through_authenticated_https">Remote repository access through authenticated https</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You can specify https URLs for remote repositories, the client will uses the JSSE system properties
configuration. It can be achieved via JVM system properties, you can read more at
<a href="http://maven.apache.org/guides/mini/guide-repository-ssl.html" class="bare">http://maven.apache.org/guides/mini/guide-repository-ssl.html</a>.</p>
</div>
<div class="sect2">
<h3 id="_using_system_properties">Using system properties</h3>
<div class="paragraph">
<p>It can configured when running the JVM: for instance:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>java -jar my-fat-jar -Djavax.net.ssl.trustStore=/my_trust_store.jks -Djavax.net.ssl.trustStorePassword=somepassword</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_programmatically_2">Programmatically</h3>
<div class="paragraph">
<p>To configure the HTTPS property, use:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">System.setProperty("javax.net.ssl.trustStore", "/my_trust_store.jks");
System.setProperty("javax.net.ssl.trustStorePassword", "somepassword");</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that programmatic configuration must be done before using the underlying Aether client (so before
instantiating the <code><a href="../../apidocs/io/vertx/maven/MavenVerticleFactory.html">MavenVerticleFactory</a></code>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_remote_repository_access_through_proxies">Remote repository access through proxies</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_using_system_properties_2">Using system properties</h3>
<div class="paragraph">
<p>Repositories can be accessed using an http proxy using the <code>vertx.maven.httpProxy</code> and <code>vertx.maven.httpsProxy</code>.
The former configures a proxy for remote http repositories and the later configures a proxy for remote http repositories.</p>
</div>
</div>
<div class="sect2">
<h3 id="_programmatically_3">Programmatically</h3>
<div class="paragraph">
<p>You can also configure the repositories programmatically using the
<code><a href="../../apidocs/io/vertx/maven/ResolverOptions.html#setHttpProxy-java.lang.String-">setHttpProxy</a></code> and
<code><a href="../../apidocs/io/vertx/maven/ResolverOptions.html#setHttpsProxy-java.lang.String-">setHttpsProxy</a></code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">vertx.registerVerticleFactory(new MavenVerticleFactory(
    new ResolverOptions().setHttpProxy(proxy))
);</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_configuring_authentication">Configuring authentication</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Basic authentication can be achieved by adding a username and/or password in the repository or proxy configuration.
For instance <code><a href="http://julien:secret@myrepository.com/" class="bare">http://julien:secret@myrepository.com/</a></code> will configure to use <code>julien</code> username and <code>secret</code>
password if the remote server needs authentication. Proxies are also supported.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_configuring_remote_snapshot_refresh_policy">Configuring Remote Snapshot Refresh Policy</h2>
<div class="sectionbody">
<div class="paragraph">
<p>By default <em>SNAPSHOT</em> dependencies are updated once a day. This behavior can be modified using the system property
<code>vertx.maven.remoteSnapshotPolicy</code>. This can be set to <code>always</code> to ensure <em>SNAPSHOT</em> dependencies are updated every
time, <code>daily</code> to update just once a day, which is the default, or to <code>never</code> to ensure they are never updated.</p>
</div>
<div class="paragraph">
<p>It can also be set to <code>interval:X</code> where <code>X</code> is the number of minutes to allow before updating a <em>SNAPSHOT</em>
dependency.</p>
</div>
<div class="paragraph">
<p>The refresh policy can also be configured from the <code><a href="../../apidocs/io/vertx/maven/ResolverOptions.html">ResolverOptions</a></code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">vertx.registerVerticleFactory(new MavenVerticleFactory(
    new ResolverOptions().setRemoteSnapshotPolicy("never"))
);</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_customizing_the_resolver">Customizing the resolver</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You can create an instance of
<code><a href="../../apidocs/io/vertx/maven/MavenVerticleFactory.html">MavenVerticleFactory</a></code> using your own <code><a href="../../apidocs/io/vertx/maven/Resolver.html">Resolver</a></code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">vertx.registerVerticleFactory(new MavenVerticleFactory(myResolver)
);</code></pre>
</div>
</div>
</div>
</div>

        

        
          <div id="footer">
            <div id="footer-text">
              
                Last updated 2016-09-12 08:38:04 CEST
              
              
            </div>
          </div>
        
      </div>
    </div>
  </div>
</div>

<footer>
  <div class="container">
    <div class="row">
      <div class="col-xs-6 col-sm-3 col-md-3 col-lg-2">
        <h2>Vert.x</h2>
        <ul class="list-unstyled">
          <li><a href="http://vertx.io/">Home</a></li>
          <li><a href="http://vertx.io/download/">Download</a></li>
          <li><a href="http://vertx.io/docs/">Documentation</a></li>
          <li><a href="https://github.com/vert-x3/wiki/wiki">Wiki</a></li>
          <li><a href="http://vertx.io/blog/">Blog</a></li>
          <li><a href="http://vertx.io/vertx2/" class="vertx-2-link">Vert.x 2</a></li>
        </ul>
      </div>
      <div class="col-xs-6 col-sm-3 col-md-3 col-lg-2">
        <h2>Community</h2>
        <ul class="list-unstyled">
          <li><a href="http://vertx.io/community/">Help &amp; Contributors</a></li>
          <li><a href="http://vertx.io/materials/">Learning materials</a></li>
          <li><a href="https://groups.google.com/forum/?fromgroups#!forum/vertx">User Group</a></li>
          <li><a href="https://groups.google.com/forum/?fromgroups#!forum/vertx-dev">Developer Group</a></li>
        </ul>
      </div>

      <div class="col-xs-12 col-sm-6 col-lg-offset-2 col-md-6 copyright">
        <p>Vert.x is open source and dual licensed under the <a href="https://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License 1.0</a> and <a href="https://www.apache.org/licenses/LICENSE-2.0.html">Apache License 2.0</a>.</p>
        <p>This website is licensed under the <a href="http://creativecommons.org/licenses/by-sa/3.0/">CC BY-SA 3.0 License</a>.<br>
        Design by <a href="http://www.michel-kraemer.com">Michel Kr&auml;mer</a>. <a href="http://www.entypo.com">Entypo pictograms</a> by Daniel Bruce.</p>
        <div class="row">
          <div class="col-xs-12 col-lg-offset-1 col-md-5">
            <a href="http://eclipse.org">
            <img class="logo eclipse-logo" src="http://vertx.io/assets/eclipse_logo_grey_small.png" width="204" height="48">
            </a>
          </div>
          <div class="col-xs-12 col-md-offset-2 col-lg-offset-0 col-md-5">
            <a href="http://cloudbees.com">
            <img class="logo cloudbees-logo" src="http://vertx.io/assets/Button-Built-on-CB-1-grey.png" width="180" height="48">
           </a>
          </div>
          <div class="col-xs-12 col-md-offset-2 col-lg-offset-1 col-md-5 jprofiler">
            <a href="http://www.ej-technologies.com/products/jprofiler/overview.html"
            style="text-decoration:none">
            <img class="logo jprofiler-logo" src="http://vertx.io/assets/jprofiler-logo.png" width="48" height="48"><span class="jprofiler-logo">&nbsp; JPROFILER</span>
            </a>
          </div>
        </div>
      </div>
    </div>
  </div>
</footer>

<script src="http://static.jboss.org/theme/js/libs/jquery/jquery-1.9.1.min.js"></script>
<script src="http://vertx.io/javascripts/bootstrap.min.js"></script>
<script src="http://vertx.io/javascripts/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>



<script src="http://vertx.io/javascripts/sidebar.js"></script>


</body>
</html>
